<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
    <title>Untitled Page</title>
<style type="text/css">
body {
    margin:0;
    padding:0;
	font-family: Verdana,"Trebuchet MS", Arial, Helvetica, sans-serif;
    font-size: 62.5%;
    color: #333;
    background: #fff;
	letter-spacing:.10em;
}
.quote {
    border: 0px;
    margin:0;
    padding: 2px 0px 2px 10px;
	font-family: Verdana,"Trebuchet MS", Arial, Helvetica, sans-serif;
    font-size: 1em;
    color: #fff;
    background: #3F7EC2;
	letter-spacing:.10em;
}
</style>
</head>
<body>

<div>
<b>One example to rule them all</b>
<br/>
Cut and paste this url in any web browser (Explorer, Firefox, Safari, or whatever), look at the parts forming the url, and notice what the browser show as an answer.
<p/>
<textarea style="width:100%;" type="text" class="quote" cols="100" size="100">
http://dev.fricchettone.com/api.aspx?hostkey=AsExYaRgXeHbIvSlWjIoBoJ288W&command=signon&username=clarinetto&password=a85f4b2d2e473d639013155c5dfcd16a
</textarea>
<div style="height:1.2em;"></div>
<b>Let's give a closer look at this url/request</b>
<p />
<span class="quote">
http://dev.fricchettone.com/api.aspx
</span>
<br />
This is the web address (domain+page) of the staging environment, it's the base address to use for every call to freak http api staging environment.
<br />The staging environment is a sandbox where you can play with the api and familiarize with it.
<p/>

<span class="quote">
hostkey=AsExYaRgXeHbIvSlWjIoBoJ288W&command=signon
</span>
<span class="quote">
&username=clarinetto&password=a85f4b2d2e473d639013155c5dfcd16a
</span>
<br />This is the query string which describe the specific freak http api call and it's
    split in different parts.
<br />
<ul>
<li><b>hostkey</b>, is a key you generate <a href="/askkey.aspx">here</a>, it allow the api to identify you whenever you call a command/method, if you are familiar with google api key, or yahoo api key, it's the same concept, the very first thing you should do to start using the api is generate a key for your application;</li>
<li><b>command</b>, is the name of the command/method you are calling, it this example is <i>signon</i> to log-in a user, the api verify the credential (username and password) you are giving and answer appropriately;</li>
<li><b>username</b>, is specific of this command, it's the username of the user you want to login;</li>
<li><b>password</b>, is specific of this command, it's the password (hashed with md5) of the user you want to login;</li>
</ul>
<p/>

<div style="height:1.2em;"></div>
<b>Now let's give a look at the answer we got.</b>
<p />
<textarea style="width:100%;" type="text" class="quote" cols="100" rows="3">
<freak>
<host name="213.156.52.122" hostkey="AsExYaRgXeHbIvSlWjIoBoJ288W" error="101" message="Host name or Host Key not valid!"/>
</freak>
</textarea>
<br />
Your answer will display a different "name", since your request come from a different host, but unless you have already generated a hostkey for your host and replaced it in the request query string, you got this error message.
The answer is always in XML form, the root tag is always &lt;freak&gt;, the children tags have different names according to context, whatever structure the answer have the first children of the root tag should not contain the attribute "error" and "message". Whatever XML answer you get, if there's a "error" attribute in the first child of the root tag, something went wrong, and this is the case.
<br />
<b>In this case the &lt;host&gt; tag is answered back</b>, with the following attributes:
<ul>
<li><b>name</b>, identify the source of the request in the form of dns name/ip address stored in the HTTP header of the request</li>
<li><b>hostkey</b>, hostkey is the key received from the api through the url/request query string</li>
<li><b>error</b>, if present something went wrong, the unique error number identify what went wrong, the full list of the possible errors is here: <a href="http://dev.fricchettone.it/ErrorMessages.xml">http://dev.fricchettone.it/ErrorMessages.xml</a>;</li>
<li><b>message</b>, a verbose error message associated with the error number given by the "error" attribute;</li>
</ul>
Now to make it work, <a href="/askkey.aspx">go here to generate a key for your host</a>, and try again, just cut and paste the request replacing the hostkey with your generated key.
<p/>

</div>

</body>
</html>
